Collection of Internet/Collection of Internet.iso/faq/news/macintos/programm/part2

Internet Message Format | 1993-08-30 | 26.6 KB

Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!pad-thai.aktis.com!pad-thai.aktis.com!not-for-mail
From: [e-mail] (Daryl Spitzer)
Newsgroups: comp.sys.mac.programmer,news.answers
Subject: Comp.Sys.Mac.Programmer FAQ Part 2/2 (1/12/93)
Supersedes: <macintosh/programmer-faq/[e-mail]>
Followup-To: poster
Date: 31 Aug 1993 00:00:16 -0400
Organization: none
Lines: 743
Sender: [e-mail]
Approved: [e-mail]
Distribution: world
Expires: 21 Sep 1993 04:00:09 GMT
Message-ID: <macintosh/programmer-faq/[e-mail]>
References: <macintosh/programmer-faq/[e-mail]>
Reply-To: [e-mail]
NNTP-Posting-Host: pad-thai.aktis.com
Summary: Frequently Asked Questions list for comp.sys.mac.programmer
Keywords: frequently asked questions faq
X-Last-Updated: 1993/01/20
Xref: senator-bedfellow.mit.edu comp.sys.mac.programmer:68127 news.answers:11922

Archive-name: macintosh/programmer-faq/part2
Last-modified: 1993/01/12


                     +---------------------------------+
                     | Frequently Asked Questions List |
                     |   for Comp.Sys.Mac.Programmer   |
                     |         January 12, 1993        |
                     |            PART  TWO            |
                     +---------------------------------+


This FAQ list is automatically posted once a week to comp.sys.mac.programmer.
It is also available via anonymous ftp from ftp.cs.uoregon.edu [128.223.8.8]
(user name 'anonymous', your internet address as password) in the files
/pub/mac/csmp-faq-1 and /pub/mac/csmp-faq-2.

This FAQ list is maintained by Daryl Spitzer.  He can be reached at the
following addresses:

   Internet:  [e-mail]
   SnailMail: 203 - 1385 West 12th Avenue
              Vancouver, BC  (Canada)
              V6H 1M2

The purpose of the FAQ list is to answer some of the most common questions
asked on this group, and to refer people left with unanswered questions to
available sources of additional help.  You should read the FAQ list before
posting to comp.sys.mac.programmer.

Submissions, comments, etcetera, should be sent to Daryl Spitzer, as above.
All such material sent will be considered to have entered the public domain
(and will be subject to editing) unless specific text to the contrary
accompanies the message (which may render the submission unusable).



                         Changes since August 3, 1992
                         ----------------------------

 - the keeper of the FAQ is now Daryl Spitzer ([e-mail])

 - 1.2  Debuggers:
    added Fritz Anderson's description of SourceBug

 - 2.1  The Associates and Partners Programs:
    new description, DEVHOTLINE is no longer a valid AppleLink address

 - 2.3  APDA
    new address and telephone numbers

 - 3.1.1  Technical Books
    new Inside Macintosh volumes

 - 3.1.3  Periodicals:
    MacTutor is now MacTech




                              Table of Contents
                              -----------------

Part One  (separate file)
---------------------

  I.    Development Software
          1. Compilers
          2. Debuggers
          3. Other Tools

  II.   Apple Developer Programs
          1. The Associates and Partners Programs
          2. Apple Developer University
          3. APDA
          4. Developer CDs

  III.  Sources of Information
          1. Books and Periodicals
               1. Technical Books
               2. Teaching Books
               3. Periodicals
          2. Mailing Lists
               1. Comp.Sys.Mac.Programmer Digest
               2. Think Class Library Discussion
               3. MacPsych
          3. Miscellaneous
               1. Usenet Mac Programmer's Guide (UMPG)
               2. Kent Sandvik's Frequently Asked MPW C++ and MacApp
Questions
               3. Comp.Sys.Mac.FAQ

  IV.   Archive Sites
          1. ftp.apple.com [130.43.2.3]
          2. sumex-aim.stanford.edu [36.44.0.6]
          3. rascal.ics.utexas.edu [128.83.138.20]
          4. mac.archive.umich.edu [141.211.164.153]
          5. ftp.cs.uoregon.edu [128.223.8.8]
          6. ics.uci.edu [128.195.1.1]
          7. ftp.brown.edu [128.148.176.55]
          8. comp.binaries.mac [newsgroup]

  V.    One-liners
          1. The Main Loop and Events
          2. Menus
          3. Resources
          4. Windows, Alerts, and Dialogs
          5. Drawing
          6. Files
          7. Interrupts and VBL Tasks
          8. Handles and Pointers
          9. General


Part Two  (this file)
-------------------------

  VI.   Specific Questions Answered
          1. The Main Loop and Events
               1. How do you tell if a specific key is being pressed?
               2. How can I get millisecond timing from the keyboard
                  (or mouse)?
          2. Menus
               1. When do you put an ellipsis on the end of a menu item?
               2. How do I get the menubar to disappear and re-appear?
               3. What's the difference between the resource ID of a 'MENU'
                  resource and the menuID field of that resource?
          3. Windows, Alerts, and Dialogs
               1. How do you put a border around the default button in a
                  dialog?
          4. Drawing
               1. What is the fastest way to paint one pixel on the screen?
               2. How do you draw directly into a pixmap without using
                  QuickDraw?
               3. How do you draw directly onto the screen without using
                  QuickDraw?
               4. What RGB value does the system use for dimmed buttons,
                  menus and window titles?
          5. Files
               1. Why is the File Manager so hard to use?
               2. How do you get a full pathname?
               3. How do you set the SFGet/PutFile directory?
               4. How do you access the application's data fork?
          6. Handles and Pointers
               1. When should I call MoveHHi?
               2. Why does malloc/calloc keep crashing or returning NULL in
                  Think C?
          7. Standalone Code
               1. How do I write an INIT?
          8. General
               1. How do I register signatures and file types with Apple?
               2. How do I go about writing serial port communications?


  VII.  Eternal Debates:
          1. Why doesn't the Mac do preemptive multitasking?



=============================================================================


                 ===========================================
                   Section VI: Specific Questions Answered
                 ===========================================



6.1  The Main Loop and Events
-----------------------------


----------------------------------------------------------
6.1.1  How do you tell if a specific key is being pressed?
----------------------------------------------------------

Use GetKeys.  GetKeys fills a 16-byte KeyMap structure with the state of
every key.  Each bit represents a single key on the keyboard; 1 means the
key is down, 0 means it is up.  Note that there can be a maximum of seven
keys being pressed at a time - any of the modifier keys plus at most two
other keys.

Here's an example in C:

Boolean IsKeyDown(
    unsigned short theKey )  // a keyboard-specific scan code for a key
{

    unsigned char  keyMap[16];

    GetKeys( (void *) keyMap );
    return ((keyMap[theKey>>3] >> (theKey & 7)) & 1);

}



-----------------------------------------------------------------------------
6.1.2  I'm writing a psychology experiment.  How can I get millisecond timing
       from the keyboard (or mouse)?
-----------------------------------------------------------------------------

The simple answer is that you can't.  Although the new time manager can call
routines every couple of microseconds, input goes through the event manager,
which only posts events about every 16 milliseconds.  Thus, even if you poll
the keyboard every 30 microseconds, you will not get better than 16 ms.
resolution.  If you really need millisecond accuracy, you need to use
external hardware.

The good news is that you probably don't need better than 16 ms. resolution
anyway.  Measuring with 16 ms. accuracy only increases the standard deviation
of your RT means by about 4.8 msec.  Read: Ulrich, R. and Giray, M. (1989).
Time resolution of clocks: Effects on reaction time measurement -- Good news
for bad clocks.  British Journal of Mathematical and Statistical Psychology,
42, 1-12.

By the way, there is a mailing list dedicated to running psychology
experiments on the Mac.  It frequently gets tied up in arguments about
millisecond timing.  The address to write to is [e-mail].




6.2  Menus
----------


-------------------------------------------------------------
6.2.1  When do you put an ellipsis on the end of a menu item?
-------------------------------------------------------------

Put an ellipsis (...) at the end of any menu item which requires more
information in order to complete or simply displays information.  Usually
this involves a dialog of some kind, be it modal or non modal.



-----------------------------------------------------------
6.2.2  How do I get the menubar to disappear and re-appear?
-----------------------------------------------------------

A set of routines to do this in Pascal can be found in the Usenet
Macintosh Programmer's Guide.  You can also ftp some sample code in C
from skinner.cs.uoregon.edu in /pub/mac/menu-bar.c.



-----------------------------------------------------------------------------
6.2.3  What's the difference between the resource ID of a 'MENU' resource and
       the menuID field of that resource?
-----------------------------------------------------------------------------

The resource ID of a 'MENU' resource is just the resource ID - it has no
hidden meaning.  What is normally expected by beginning programmers is that
the number that MenuSelect and MenuKey return is the resource ID of the menu.
In fact, the number returned is the value of the menuID field of the menu,
and has no relation to the resource ID of the menu.  You can set the menuID
to any number you want, but by convention it is expected to be the same as
the resource ID of the menu.  (You can change this value in ResEdit by
opening the menu you wish to change, and selecting 'Edit Menu & MDEF ID...'
from the MENU menu.)




6.3  Windows, Alerts, and Dialogs
---------------------------------


---------------------------------------------------------------------
6.3.1  How do you put a border around the default button in a dialog?
---------------------------------------------------------------------

The most common way to do this is to create a dummy user item in the dialog,
and use SetDItem to install a procedure that outlines the default button.
The dialog's "Initially visible" bit should be false and you should call
ShowWindow before calling ModalDialog; otherwise, if the button is very tall,
part of the outline won't be drawn.  Here is an example in C:


/* This function draws a border around dialog item #1 */

pascal void OutlineDefault(
    DialogPtr theDialog,
    short     theItem )
{

    Rect     itemRect;
    Handle   itemHandle;
    short    itemType;
    short    diameter;

    GetDItem( theDialog, 1, &itemType, &itemHandle, &itemRect );
    diameter = (itemRect.bottom - itemRect.top) / 2 + 6;
    if ( diameter < 16 )
        diameter = 16;
    PenSize( 3, 3 );
    InsetRect( &itemRect, -4, -4 );
    FrameRoundRect( &itemRect, diameter, diameter );

}



/* Assume myDialog has been initialized, and item #4 is the dummy
   user item for outlining the default button.  The following lines
   install the outlining procedure OutlineDefault into the user
   item, so that OutlineDefault will be called by the Dialog Manager
   each time the dialog needs to be redrawn.  Depending on your
   compiler, you may have to cast OutlineDefault to a Handle. */

GetDItem( myDialog, 4, &itemType, &itemHandle, &itemRect );
SetDItem( myDialog, 4, itemType, OutlineDefault, &itemRect );




6.4  Drawing
------------


----------------------------------------------------------------
6.4.1  What is the fastest way to paint one pixel on the screen?
----------------------------------------------------------------

Using QuickDraw, the fastest way to draw one pixel is
   MoveTo( x, y );
   Line( 0, 0 );
making sure that the pen size is 1 by 1.  This is about twice as fast as
setting the pen size to 0 by 1 or 1 by 0 and calling Line( 1, 0 ) or
Line( 0, 1 ), respectively.  I'm not sure why....

See below for how to draw a pixel without using QuickDraw.



----------------------------------------------------------------------
6.4.2  How do you draw directly into a pixmap without using QuickDraw?
----------------------------------------------------------------------

As an example, here is a routine that paints a single pixel in a pixmap.
To use this procedure, you just have to know what 'value' to pass in.  This
depends on the current bit-depth of 'thePixMap.'  The rightmost n bits of
'value' are used for the pixel value for depth = n.  For depths of eight or
less, the value of each pixel is an index into a color table.  For depth =
16,
each 16-bit pixel is interpreted as an RGB value, as follows:

         Bit: 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
       Value:  R  R  R  R  R  G  G  G  G  G  B  B  B  B  B  U

where R = Red, G = Green, B = Blue, and U = Unused.  For depth = 32, each
32-bit pixel is interpreted as an RGB value as follows:

         Bit: 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16
       Value:  A  A  A  A  A  A  A  A  R  R  R  R  R  R  R  R

         Bit: 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
       Value:  G  G  G  G  G  G  G  G  B  B  B  B  B  B  B  B

where R = Red, G = Green, B = Blue, and A = Alpha.



void SetPixel(
    short           x,
    short           y,
    long            value,
    PixMapHandle    thePixMap )
{

    unsigned long   rowBytes;
    unsigned char   mask;
    unsigned char   shiftBits;
    unsigned char   *thePixel;
    unsigned char   pixelDepth;
    char            mode = true32b;
    Boolean         swapMode;
        swapMode = PixMap32Bit( thePixMap );

    LockPixels( thePixMap );

    rowBytes = (unsigned long) ((*thePixMap)->rowBytes & 0x1fff);
    thePixel = (unsigned char *) GetPixBaseAddr( thePixMap );

    pixelDepth = (*thePixMap)->pixelSize;

    switch ( pixelDepth ) {
            case 1:
        case 2:
        case 4:
        case 8:

            thePixel += (rowBytes * y) +
                        (((unsigned long) pixelDepth * x) / 8L);

            shiftBits = ((8 - pixelDepth) - ((x * pixelDepth) % 8));

            mask = (unsigned char) ((1 << pixelDepth) - 1) << shiftBits;

            if ( swapMode ) {
                SwapMMUMode( &mode );
            }

            *thePixel &= ~mask;
            *thePixel |= (unsigned char) value << shiftBits;

            break;


        case 16:

            thePixel += (rowBytes * y) + (2L * x);

            if ( swapMode ) {
                SwapMMUMode( &mode );
            }

            *((unsigned short *)thePixel) = (unsigned short) value;

            break;


        case 32:

            thePixel += (rowBytes * y) + (4L * x);

            if ( swapMode ) {
                SwapMMUMode( &mode );
            }

            *((unsigned long *)thePixel) = value;

            break;


        default:
            break;

    }

    if ( swapMode ) {
        SwapMMUMode( &mode );
    }

    UnlockPixels( thePixMap );

}



------------------------------------------------------------------------
6.4.3  How do you draw directly onto the screen without using QuickDraw?
------------------------------------------------------------------------

Get the pixmap for the monitor that you want to draw on, and send it to the
above procedure.  For example, to draw a red dot at position 10,10 on the
main screen (if the main screen is in 32-bit mode):

   GDHandle   theDevice;

   theDevice = GetMainDevice();

   SetPixel( x, y, 0x00FF0000, (*theDevice)->gdPMap );

If you are drawing directly to the screen, you should always wrap your
drawing with calls to ShieldCursor and ShowCursor.  Some monitors such
as the Radius Pivot series keep a virtual screen, and they don't update
the real screen unless they have to.  When you write directly to the
screen, you're actually writing to the virtual screen, and your drawing
won't show up on the real screen until the system has some other reason
to update the monitor.  Calling ShieldCursor each time you draw will
force these systems to update the real screen when you expect them to.



-----------------------------------------------------------------------
6.4.4  What RGB value does the system use for dimmed buttons, menus and
       window titles?
-----------------------------------------------------------------------

The gray color does not have a fixed RGB value.  It is a weighted average of
the foreground and background colors.  To obtain the appropriate 'gray' color
for a given foreground and background color, use the Palette Manager routine
GetGray (documented in Inside Macintosh Volume VI).

pascal Boolean GetGray( GDHandle device, const RGBColor *backGround,
                        RGBColor *foreGround )
  = {0x303C,0x1219,0xAAA2};

If at least one gray or intermediate color is available, GetGray stores the
color in foreGround and returns true.  If no gray is available, or, if you
supplied two colors, no third distinguishable color is available, the
foreGround parameter is unchanged and the function returns false.

GetGray is not available in older versions of the system.  Use Gestalt to
determine whether it is available.




6.5  Files
----------


----------------------------------------------
6.5.1  Why is the File Manager so hard to use?
----------------------------------------------

Its always those pesky wdrn's that are the problem.  Here is a summary of
some of the things to know:

    vrn = volume reference number
          (small negative number; e.g. -2)
    wdrn = working directory reference number
           (large negative number; e.g. -32123)
    dirID = directory ID
            (small (but long integer!) positive number; e.g. 4123)

    - vrn's and wdrn's can be used interchangably for the most part.
    - A vrn represents either a volume, or the root directory of a volume.
    - A wdrn represents a directory on a volume.
    - A dirID represents nothing without a vrn or a wdrn.
    - A dirID overrides the directory otherwise specified by the vrn or wdrn
      unless it's zero, in which case it's ignored.  If it is 2 it specifies
      the root directory of the volume.
    - You should always use vrn,dirID pairs. To convert a wdrn into a
      vrn,dirID pair use GetWDInfo, which returns the vRefNum, the dirID and
      the procID of the wdRefNum.  The procID is almost always 'ERIK'.
    - You can also use GetVol/SetVol to convert volume names to/from vrns.
    - To store a vrn,dirID pair (between invocations of a program) convert
      the vrn to a volume name & creation date (for verification) and store
      them and the dirID (and a filename perhaps).



--------------------------------------
6.5.2  How do you get a full pathname?
--------------------------------------

Take a look at Tech Note #238, available from APDA (and other places).  It
tells you everything you need to know to get a full pathname, and why you
should, in general, use a volume name, dirID, filename (and perhaps volume
creation date) triple instead.  Also check out the code snippets available
from ftp.apple.com et al.  There are a couple of snippets that give code to
get a full pathname, as well as many other cool file manager tricks.



--------------------------------------------------
6.5.3  How do you set the SFGet/PutFile directory?
--------------------------------------------------

To set the directory that is displayed by SFGet/PutFile, stuff the volume
reference number into SFSaveDisk, and the dirID into CurDirStore.

     CurDirStore = $398;   Current dirID from Standard File (long)
     SFSaveDisk = $214;    Negative of current vRefNum



-----------------------------------------------------
6.5.3  How do you access the application's data fork?
-----------------------------------------------------

Call CurResFile when the application starts up.
Call PBGetFCBInfo to convert that refNum into a vRefNum, dirID and name.
Call HOpen with the vRefNum, dirID, and name to open up your data fork.




6.6  Handles and Pointers
-------------------------


----------------------------------
6.6.1  When should I call MoveHHi?
----------------------------------

MoveHHi is an expensive operation; calling it when you don't need to can
significantly slow down your program.  Additionally, over-calling of MoveHHi
can fragment the top of your heap.  Call MoveHHi before locking a handle that
is followed by some memory allocation.  To efficiently move a handle high in
the heap and then lock it, you might want to call HLockHi, a call new with
MPW 3.2 and THINK C 5.0 (probably THINK Pascal 4.0 as well).



-------------------------------------------------------------------------
6.6.2  Why does malloc/calloc keep crashing or returning NULL in Think C?
-------------------------------------------------------------------------

#include <stdlib.h>

Explanation:  In THINK C, parameters and return values are 2-byte ints by
default, which causes the value passed to malloc to be $10000 times as large
as you think it is, and causes the upper bytes of the return value to be
zeroed.  Including stdlib includes a prototype which overrides the defaults.

Another common cause of problems with malloc is overwriting the end of a
string, such as only mallocing the size of the string and then writing the
string plus a null into the malloc'd space.  Think's malloc algorithm stores
block size information in space adjacent to the storage it allocates, so
overwriting the storage tends to cause havoc. The problem may not show
immediately since it will probably be the next malloc that encounters
problems.




6.7  Standalone Code
--------------------


------------------------------
6.7.1  How do I write an INIT?
------------------------------

There is a simple INIT (SetWindow INIT) with source code and explanations in
the Usenet Macintosh Programmer's Guide.  There is also a chapter on writing
system extensions in Macintosh Programming Secrets (2nd Ed.).  Be sure to
check out the ftp sites (especially ftp.apple.com) for sample inits.




6.8  General
------------


--------------------------------------------------------------
6.8.1  How do I register signatures and file types with Apple?
--------------------------------------------------------------

Registering a signature and file type is free, and you don't have to be an
Apple Partner or Associate.  You can ftp the registration form from
ftp.apple.com; it's available as
     /dts/mac/registration/creator-file-type-form.txt.



-------------------------------------------------------------------------
6.8.2  How do I go about writing serial port communications?

These days, it is best to use the new Comunications Toolbox (CTB).  By
utiizing the CTB, you will be able to write your code to a single
specification, and the code will work with all current CTB "tools" and all
future CTB tools. The CTB tools allow programmers to extend the CTB's
functionality. There is a tool for each facet of the communications puzzle:
Connection Tools, Terminal Tools, and File Transfer Tools.

For example, once I have written a piece of code that uses the Serial tool to
connect me to a terminal server, combined with the VT102 Tool to emulate a
vt102 terminal, and the XMODEM Macbinary Tool to transfer files, the same
code will work with Apple Modem Tool, TCP/IP, AppleTalk ADSP, ISDN, X.25, and
all future Connection Tools. Further, the terminal can emulate a VT320,
ASCII, or other terminals. Files may be transfered with XMODEM, TEXT, and
soon ZMODEM and Kermit protocols.

The disadvantage of the CTB is that you must limit yourself to the
specification of the Connection, Terminal, and File Transfer interfaces.
These limitations are *rarely* a problem, but clearly something like a FAX
interface program or real time data analyzer, would have to seriously
consider the interfaces before committing.

For most standard communications applications, such as terminal emulators,
Bulletin Board Systems, etc., the CTB is the correct choice.

You can only get the CTB development kit from APDA.  It is affordable,
somewhere just under $100.  This includes working sample code.





                      ================================
                        Section VII: Eternal Debates
                      ================================


These questions have no final answers.  They pop up every few months and
waste a tremendous amount of valuable network resources on discussions
that will never be resolved.  Most people would be happy if they were
never discussed again in this newsgroup.


7.1  Why doesn't the Mac do preemptive multitasking?
----------------------------------------------------

Pro-preemptives claim the current scheme is too vulnerable to ill-behaved
applications and too much trouble for application writers.  Anti-
preemptives claim that preemptive multitasking would reduce interactive
response, and that the current cooperative system works well.





                       ==============================
                         Credits / Acknowledgements
                       ==============================


Many thanks to Ben Haller, who started this whole thing, and did quite a lot
of work on this posting before handing it off to Michael A. Kelly.  Many
thanks to Michael A. Kelly also, for all his work in establishing and
maintaining this FAQ (in addition to continuing to keep the
Comp.Sys.Mac.Programmer Digest) before passing the baton.

Thanks to these people for proofreading this list during its development:
    Ben Haller
    Wally Wedel
    John B. Matthews
    Patrick Beard
    Steve Zellers

Thanks to Chris Webster for the one-liners.

Thanks to Peter Lewis for the answers to the following specific questions:
    6.2.1  When do you put an ellipsis on the end of a menu item?
    6.5.1  Why is the File Manager so hard to use?
    6.5.2  How do you get a full pathname?
    6.5.3  How do you set the SFGet/PutFile directory?

Thanks to Greg Ferrar for the review on TMON Pro.

Thanks to John Rinaldo for the review on Jasik's Debugger.

Thanks for Fritz Anderson for his descriptions of SourceBug and the new
Inside Macintosh volumes.

And thanks to everyone who has offered suggestions or constructive
criticism....  Keep those comments coming!




--
-------------------------------------------------------------------
 [e-mail]     "Life isn't just, life just is."
         [e-mail]              -- Me  (I think.)
-------------------------------------------------------------------